home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / cat3 / optarg.3 < prev    next >
Encoding:
Text File  |  1993-03-03  |  5.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GETOPT(3)           MINTLIB LIBRARY FUNCTIONS           GETOPT(3)
  5.  
  6.  
  7. N✓NA✓AM✓ME✓E
  8.        getopt - get option letter from argument vector
  9.  
  10. S✓SY✓YN✓NO✓OP✓PS✓SI✓IS✓S
  11.        #include <unistd.h>
  12.  
  13.        int getopt(int argv, char * const *argv, const char *optstring);
  14.  
  15.        extern char *optarg;
  16.  
  17.        extern int optind;
  18.  
  19.        extern int opterr;
  20.  
  21. D✓DE✓ES✓SC✓CR✓RI✓IP✓PT✓TI✓IO✓ON✓N
  22.        getopt returns the next option letter in argv that matches
  23.        a letter in optstring. It supports all the  rules  of  the
  24.        UN*X  System  V  command  syntax standard (see the section
  25.        RULES below).  All new programs that wish to adhere to the
  26.        command  syntax  standard should use getopt to parse posi-
  27.        tional parameters and check for options that are legal for
  28.        that command.
  29.  
  30.        optstring  must  contain  the  option  letters the command
  31.        using getopt will recognize; if a letter is followed by  a
  32.        colon,  the  option  is  expected  to have an argument, or
  33.        group of arguments, which must be  separated  from  it  by
  34.        white space.
  35.  
  36.        optarg is set to point to the start of the option-argument
  37.        on return from getopt.
  38.  
  39.        getopt places in optind the argv index of the  next  argu-
  40.        ment  to  be processed. optind is external and is initial-
  41.        ized to 1 before the first call to getopt.
  42.  
  43.        When all options have been  processed  (i.e.,  up  to  the
  44.        first  non-option  argument), getopt returns EOF. The spe-
  45.        cial option "--" may be used to delimit  the  end  of  the
  46.        options; when it is encountered, EOF will be returned, and
  47.        "--" will be skipped.
  48.  
  49. D✓DI✓IA✓AG✓GN✓NO✓OS✓ST✓TI✓IC✓CS✓S
  50.        getopt prints an  error  message  on  standard  error  and
  51.        returns  a  question mark (?) when it encounters an option
  52.        letter not included in  optstring  or  no  option-argument
  53.        after  an  option that expects one. This error message may
  54.        be disabled by setting opterr to 0.
  55.  
  56. R✓RU✓UL✓LE✓ES✓S
  57.        The UN*X System V command standard contains the  following
  58.        rules:
  59.  
  60.         1.  Command names must be between two and nine characters
  61.  
  62.  
  63.  
  64. MiNT docs 0.1              3 March 1993                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GETOPT(3)           MINTLIB LIBRARY FUNCTIONS           GETOPT(3)
  71.  
  72.  
  73.        long.
  74.         2. Command names must include only lower-case letters and
  75.        digits.
  76.         3. Option names must be one character long.
  77.         4. All options must be preceded by "-".
  78.         5. Options with no arguments may be grouped with a single
  79.        "-".
  80.         6. The first option-argument following an option must be
  81.            preceded by white space.
  82.         7. Option-arguments cannot be optional.
  83.         8. Groups of option-arguments following an option must be
  84.        either
  85.            be separated by commas or separated by white space and
  86.        quoted
  87.            (e.g.,  -o xxx,z,yy  or  -o "xxx z yy").
  88.         9. All options must precede operands on the command line.
  89.        10.  "--"  may be used to indicate the end of the options.
  90.        11. The order of the options relative  to  another  should
  91.        not  matter.   12.  The relative order of the operands may
  92.        effect their
  93.            significance in ways determined by  the  command  with
  94.        which
  95.            they  appear.   13. "-" preceded and followed by white
  96.        space should only be used
  97.            to mean standard input.
  98.  
  99.        getopt supports rules 3-10 above; the enforcement  of  the
  100.        other rules must be done by the command itself.
  101.  
  102. E✓EX✓XA✓AM✓MP✓PL✓LE✓E
  103.        The following code fragment shows how one might process the
  104.        arguments for a command that can take the mutually exclusive
  105.        options 'a' and 'b', and the option 'o', which requires an
  106.        option-argument.
  107.  
  108.        #include <stdio.h>
  109.        #include <stdlib.h>
  110.        #include <unistd.h>
  111.        extern char *optarg;
  112.  
  113.        void main(int argc, char *argv[])
  114.        {
  115.          int  c, aflg = 0, bflg = 0, errflg = 0;
  116.          char *ofile = NULL;
  117.  
  118.          while ((c = getopt(argc, argv, "abo:")) != EOF)
  119.            switch (c)
  120.            {
  121.              case 'a':
  122.                if (bflg != 0)
  123.                  errflg++;
  124.                else
  125.                  aflg++;
  126.                break;
  127.  
  128.  
  129.  
  130. MiNT docs 0.1              3 March 1993                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GETOPT(3)           MINTLIB LIBRARY FUNCTIONS           GETOPT(3)
  137.  
  138.  
  139.              case 'b':
  140.                if (aflg != 0)
  141.                  errflg++;
  142.                else
  143.                  bflg++;
  144.                break;
  145.              case 'o':
  146.                ofile = optarg;
  147.                break;
  148.              case '?':
  149.                errflg++;
  150.            }
  151.          if (errflg != 0)
  152.          {
  153.            fprintf(stderr, "Usage:...n");
  154.            exit(1);
  155.          }
  156.          ...
  157.        }
  158.  
  159. N✓NO✓OT✓TE✓ES✓S
  160.        getopt  cannot  be  used for complicated context-sensitive
  161.        argument vector parsing.
  162.  
  163.        The UN*X System V standard may seem too  restrictive;  for
  164.        instance,  in  the  above example, '-ofile' is not allowed
  165.        ('-o file' is).
  166.  
  167.        Some systems return -1 instead of EOF; this  may  actually
  168.        make a difference on some systems.
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196. MiNT docs 0.1              3 March 1993                         3
  197.  
  198.  
  199.